TERMIOS

NAME

SYNOPSIS

DESCRIPTION

The header <termios.h> contains the definition of the termios structure and associated constants. The termios structure is passed as an argument to the tcgetattr, tcsetattr, tcdrain, tcflow, tcflush, tcsendbreak, cfgetispeed, cfgetospeed, cfsetispeed and cfsetospeed functions.

The termios Structure

The termios structure contains the following members:

        Member  Type            Description

        c_iflag         tcflag_t                Input modes
        c_oflag         tcflag_t                Output modes
        c_cflag         tcflag_t                Control modes
        c_lflag         tcflag_t                Local modes
        c_cc[NCCS]      cc_t            Control characters

Special Characters

Some characters have special functions on input or output or both. Some special characters are constants; others are defined in the c_cc array (indexed by defined constants). The interpretation of these characters is described in the following subsections. The characters and their values (as constants or c_cc expressions) are as follows:

CR

The carriage-return character: '\r'.

NL

The new-line character: '\n'.

EOF

The end-of-file character: c_cc[VEOF].

EOL

The alternate end-of-line character: c_cc[VEOL].

ERASE

The erase character: c_cc[VERASE].

KILL

The erase-line character: c_cc[VKILL].

WERASE

The erase character: c_cc[VWERASE].

REPRINT

The redisplay-input character: c_cc[VREPRINT].

INTR

The interrupt character (generates SIGINT): c_cc[VINTR].

QUIT

The quit character (generates SIGQUIT): c_cc[VQUIT].

SUSP

The suspend character (generates SIGTSTP): c_cc[VSUSP].

DSUSP

The delayed-suspend character (generates SIGTSTP): c_cc[VDSUSP].

STOP

The stop-output character: c_cc[VSTOP].

START

The start-output character: c_cc[VSTART].

DISCARD

The flush-output character: c_cc[VDISCARD].

LNEXT

The literal-next character: c_cc[VLNEXT].

QUOTE

The quote character: c_cc[VQUOTE].

MIN, TIME

MIN and TIME are not special characters, but are nevertheless stored in the c_cc array. They are, respectively, c_cc[VMIN] and c_cc[VTIME].

These special characters are only meaningful when specific flags are set. The NL, EOF, EOL, ERASE, KILL, QUOTE, WERASE, and REPRINT special characters are enabled when ICANON (in c_lflag) is set. The INTR, QUIT, SUSP, and DSUSP characters are enabled when ISIG (in c_lflag) is set. The START and STOP special characters are enabled when IXON or IXOFF (in c_iflag) is set. LNEXT and DISCARD are enabled by IEXTEN (in c_lflag).

Input Processing Modes

Each terminal device has associated with it an input queue, into which incoming data is stored by the system before being read by a process. Two styles of input processing are available, determined by whether the terminal device is in canonical mode (ICANON set) or noncanonical mode (ICANON not set).

In canonical mode input processing, terminal input is processed in units of lines. A line is delimited by the NL character, the EOF character, or the EOL character. This means that a read request will not return until an entire line has been typed (or a signal has been received). Also, no matter how many bytes are requested in the read call, at most one line will be returned. It is not, however, necessary to read a whole line at once; any number of bytes, even one, may be requested in a read without losing information. NL and EOL, when entered, are considered part of the line. EOF, on the other hand, terminates a line, but is not passed to the reader. As a consequence, an EOF received at the beginning of a line marks an empty line, which causes a read to return zero bytes (the empty line), simulating an end-of-file condition.

A line can be edited as it is entered, with the ERASE, KILL, and WERASE characters. Editing is limited to the current line, consisting of characters in the input queue that have not yet been delimited by NL, EOF, or EOL. The ERASE character deletes the last character in the current line, if there is any. The KILL character deletes all characters in the current line. The WERASE character deletes the last word in the current line. In addition, the REPRINT character causes the input queue to be redisplayed.

The QUOTE character followed by the ERASE enters the ERASE character into the input queue. The sequence QUOTE followed by KILL enters the KILL character. QUOTE has no special meaning when followed by any other character (include WERASE). (QUOTE provides compatibility with older terminal interfaces.)

In noncanonical mode input processing, input bytes are not assembled into lines, and line editing is not allowed. The values of MIN and TIME are used to determine how to process the bytes received.

MIN represents the minimum number of bytes that must be entered before a read will return. The TIME parameter gives the amount of delay, in 1/10-second increments, before a read times out and returns. There are four different cases to be considered:

MIN > 0 and TIME = 0

TIME is ignored. Data is not made available to a read request until MIN bytes have been received. A read can block indefinitely.

MIN > 0 and TIME > 0

TIME acts as an inter-byte timer that is not set until the first byte is entered and is reset after each byte. If MIN characters are received before the timer expires, the data becomes available and a read will return. It will return the smaller of MIN and the number of bytes actually read. Because the timers does not start until the first byte is received, a read can block indefinitely. Moreover, a read will always return at least 1 byte, unless interrupted by a signal.

MIN = 0 and TIME = 0

A read always returns immediately. If data has already been entered, it is available, and (up to the number of bytes requested) is returned.

MIN = 0 and TIME > 0

TIME is a timer activated as soon as the process reads. Data is made available as soon as a single byte is entered. It is not possible for a read to block indefinitely - after TIME/10 seconds, if no data has been entered, a read will return 0.

In both canonical and noncanonical modes, other special characters are available. INTR, QUIT, and SUSP generate signals (SIGINT, SIGQUIT, and SIGTSTP, respectively) to the current process group. When entered, DSUSP is placed in the input queue. When it is read by a process, SIGTSTP is generated and the DSUSP character is not passed to the process. START and STOP are used for flow control for both input and output (see IXON and IXOFF below). DISCARD causes further output to the terminal to be discarded, until another character is entered. LNEXT followed by any other character (including special characters, including LNEXT) enters that character into the input queue, disregarding any special meaning that character may have.

Input Modes

The bit-masks in c_iflag describe basic terminal input control and are composed of the bitwise inclusive OR of the following masks:

IGNCR

A received CR character is ignored (not placed on the input queue)

ICRNL

If IGNCR is not set, then a received CR is translated into NL.

INLCR

A received NL is translated into CR.

INPCK

Input parity checking is enabled. The type of parity is determined by flags in c_cflag.

IGNPAR

Characters with parity errors are ignored.

PARMRK

If IGNPAR is not set, then a byte with a framing or parity error is placed in the input queue as the 3-byte sequence: '\377', '\000', X, where X is the erroneous character.

ISTRIP

Valid input characters are first stripped to seven bits before being placed in the input queue; otherwise, all eight bits are processed.

IGNBRK

A break condition detected on input is ignored (not placed on the input queue).

BRKINT

If IGNBRK is clear, a break causes the input and output queues to be flushed. A SIGINT signal is sent to the terminal's process group. If neither IGNBRK nor BRKINT is set, a break condition is read as a single '\0'.

IXON

Start-stop output control is enabled. A received STOP character suspends output, and a received START character restarts output. When IXON is set, START and STOP characters are not read, but merely perform flow control functions. When IXON is not set, the START and STOP characters are read but have no special functions.

IXANY

When IXANY is set and output is stopped (from receiving the STOP character), output is be restarted by receiving any character. That character is processed normally.

IXOFF

If IXOFF is set, start-stop input control is enabled. The system sends one or more STOP characters to cause the terminal to stop transmitting data, to avoid overflowing the input buffer. The system also sends one or more START characters to cause the terminal to restart transmission.

IMAXBEL

If IMAXBEL is set and a character is received when the input queue is full, then a bell character (control-G) is written to the output.

Output Modes

The bit-masks in c_oflag describe the basic terminal output control and are composed of the bitwise inclusive OR of the following masks:

OPOST

If OPOST is clear, output characters are transmitted unchanged. If OPOST is set, then output processing is performed, as dictated by other c_oflag bits. In addition, if OPOST is set and the device is in canonical mode, then the ASCII EOT character (control-D) is never transmitted (for compatibility with older interfaces).

ONLCR

If ONLCR is set, an NL character is expanded into CR and NL on output.

NLDELAY, TBDELAY, ...

The delay flags supported by the tty interface (see tty(4)) are also valid as c_oflag values. Delays, however, are not supported when outputting 8-bit characters (see CSIZE below).

Control Modes

CLOCAL

The modem status lines are ignored (the terminal is assumed to be connected to the system locally). If CLOCAL is clear, the modem status lines are monitored.

CREAD

Reception of characters is enabled. Otherwise, characters will not be received.

CSTOPB

Two stop bits are sent after each character. Otherwise, only one is sent.

CSTOPB110

Two stop bits are sent if output speed is 110 baud.

CSIZE

The CSIZE bits specify the byte size in bits for both transmission and reception. Valid values are CS5, CS6, CS7 or CS8 for 5, 6, 7 or 8 bit per byte respectively.

PARENB

Parity generation and detection are enabled.

PARODD

If PARENB is set, odd parity is generated and expected. If PARODD is clear and PARENB is set, even parity is generated and expected.

PAR0

If PARODD is not set, IEXTEN (in c_lflag) is set, and PAR0 is set, then space (zero) parity is generated on output, and parity is expected on input but not checked. (PAR0 is meant to emulate the behavior of the tty(4) interface when neither EVENP nor ODDP is set.)

PAR1

If PARODD is not set, IEXTEN is set, and PAR1 is set, then even parity is generated on output, and parity is expect but unchecked on input. (PAR1 is meant to be equivalent to setting both EVENP and ODDP through the tty(4) interface.) The effect of setting both PAR0 and PAR1 is undefined.

HUPCL

When the last process that has the terminal file open terminates or closes the file, the modem control lines will be lowered and the modem connection is broken.

Local Modes

ECHO

Echoing of characters is enabled. Otherwise, characters are not echoed back to the terminal.

ECHONL

A received NL character is echoed even if ECHO is not set.

ECHOCTL

If ECHOCTL and ECHO are set, control characters will be echoed as ^X.

ECHOE

In canonical mode, an ERASE character will erase the previous character from the display, in a way determined by the flags ECHOCRT and ECHOPRT (see below). If neither ECHOCRT nor ECHOPRT is set, then a backspace character (`\b') is echoed.

ECHOCRT

If ECHOCRT is set, then erasing a deleted character will be accomplished by sending the sequence ``\b \b'' (suitable for a CRT display).

ECHOPRT

If ECHOPRT is set, deleted characters will be erased in a way appropriate for a hard-copy terminal.

ECHOK

In canonical mode, a KILL character will cause the terminal to echo the KILL character followed by a newline (unless ECHOKE is set).

ECHOKE

In canonical mode, a KILL character will cause the terminal to erase the current line from the display.

ICANON

If ICANON is set, the device is in canonical input mode. Otherwise, the device is in noncanonical input mode.

IEXTEN

IEXTEN enables the special characters LNEXT and DISCARD, as well as certain other features as described.

ISIG

If ISIG is set, the characters INTR, QUIT, SUSP, and DSUSP take on their special meaning.

NOFLSH

The input and output queues are not flushed when a signal is generated due to receipt of an INTR, QUIT, or SUSP character. If NOFLSH is clear, then generation of such a signal causes the input and output queues to be flushed.

TOSTOP

A SIGTTOU signal is generated for the process group of any background process that attempts to write to its controlling terminal. However, if the writing process has arranged to block or ignore SIGTTOU, then the signal is not generated and the output is sent. If TOSTOP is not set, then data transmitted by a write to the controlling terminal from a background process is put on the output stream.

Compatibility

The features supported by termios are a superset of those implemented by the older tty(4) interface. The two interfaces can coexist on the same device. However, mixing uses of both interfaces in the same program (e.g., using both tcsetattr and ioctl(TIOCSETP)) is not recommended.  

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO